Summary

Relaxes the environments.yaml auth-principal validator so agent developers can register an agent under a service account instead of a user identity.

• _validate_single_environment_config now requires exactly one of user_id or service_account_id in the auth.principal block (mutually exclusive). The previous validator hard-required user_id, which blocked SA registration end-to-end.
• Updates the docstring example in environment_config.py to show both shapes.

Backwards compatible: existing configs with only user_id continue to validate. Field shape mirrors what agentex-auth (SGPPrincipalContext) and SGP (x-user-id / x-service-account-id headers) already use, so no translation layer is needed between yaml and the wire.

Related PRs (ship together)

• This PR (SDK validator) — scaleapi/scale-agentex-python#332
• SGP backend — https://github.com/scaleapi/scaleapi/pull/141104
• agentex-auth — https://github.com/scaleapi/agentex/pull/333
• scale-agentex (auth cache key) — feat: add service account id to auth cache scale-agentex#210

Test Plan

• 4 new unit tests in tests/lib/cli/test_validation.py, all passing via uv run pytest:
  • user-only principal validates (backwards-compat)
  • service_account-only principal validates
  • principal with neither id is rejected with a clear error
  • principal with both ids is rejected with a "not both" error
• Existing test_environment_config.py (18 tests) still passes.
• ruff check + ruff format clean.

Greptile Summary

This PR relaxes the environments.yaml auth-principal validator to accept either user_id or service_account_id (mutually exclusive), enabling agents to be registered under a service account identity. Existing configs using only user_id are fully backwards-compatible, and four targeted unit tests cover all four principal combinations.

Important Files Changed

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[_validate_single_environment_config] --> B{principal has user_id?}
    B -- No --> C{principal has service_account_id?}
    C -- No --> D[❌ ValueError: must contain one of user_id or service_account_id]
    C -- Yes --> E[✅ SA path — skip env-name warning]
    B -- Yes --> F{also has service_account_id?}
    F -- Yes --> G[❌ ValueError: not both]
    F -- No --> H{user_id is a string?}
    H -- Yes --> I{contains env indicator?}
    I -- No --> J[⚠️ logger.warning: missing env indicator in user_id]
    I -- Yes --> K[✅ user_id path OK]
    J --> K
    E --> L[validate helm overrides if present]
    K --> L

This is a comment left during a code review.
Path: src/agentex/lib/sdk/config/validation.py
Line: 113-119

Comment:
**Missing comment on intentional skip of env-indicator warning**

The `if isinstance(user_id, str):` block silently skips the environment-name warning when `service_account_id` is used instead. This is the right call (SA IDs are pre-created UUIDs, not free-form strings), but it is non-obvious to a future maintainer who sees a codepath with no validation at all for `service_account_id`. A short inline comment would make the intent clear.

```suggestion
    # Check for environment-specific user_id patterns.
    # This warning is intentionally skipped for service_account_id: SA identifiers
    # are pre-created UUIDs whose names are not expected to encode environment info.
    if isinstance(user_id, str):
        if not any(env_name.lower() in user_id.lower() for env_name in ["dev", "prod", "staging", env_name]):
            logger.warning(
                f"User ID '{user_id}' doesn't contain environment indicator. "
                f"Consider including '{env_name}' in the user_id for clarity."
            )
```

**Rule Used:** Add comments to explain complex or non-obvious log... ([source](https://app.greptile.com/review/custom-context?memory=928586f9-9432-435e-a385-026fa49318a2))

**Learned From**
[scaleapi/scaleapi#126958](https://github.com/scaleapi/scaleapi/pull/126958)

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (2): Last reviewed commit: "better error message" | Re-trigger Greptile}

Context used:

• Rule used - Add comments to explain complex or non-obvious log... (source)

Learned From
scaleapi/scaleapi#126958